home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / lib / perl / 5.10.0 / Encode / Guess.pm < prev    next >
Encoding:
Perl POD Document  |  2009-06-26  |  9.8 KB  |  356 lines
  1. package Encode::Guess;
  2. use strict;
  3. use warnings;
  4. use Encode qw(:fallbacks find_encoding);
  5. our $VERSION = do { my @r = ( q$Revision: 2.2 $ =~ /\d+/g ); sprintf "%d." . "%02d" x $#r, @r };
  6.  
  7. my $Canon = 'Guess';
  8. sub DEBUG () { 0 }
  9. our %DEF_SUSPECTS = map { $_ => find_encoding($_) } qw(ascii utf8);
  10. $Encode::Encoding{$Canon} = bless {
  11.     Name     => $Canon,
  12.     Suspects => {%DEF_SUSPECTS},
  13. } => __PACKAGE__;
  14.  
  15. use base qw(Encode::Encoding);
  16. sub needs_lines { 1 }
  17. sub perlio_ok   { 0 }
  18.  
  19. our @EXPORT         = qw(guess_encoding);
  20. our $NoUTFAutoGuess = 0;
  21. our $UTF8_BOM       = pack( "C3", 0xef, 0xbb, 0xbf );
  22.  
  23. sub import {    # Exporter not used so we do it on our own
  24.     my $callpkg = caller;
  25.     for my $item (@EXPORT) {
  26.         no strict 'refs';
  27.         *{"$callpkg\::$item"} = \&{"$item"};
  28.     }
  29.     set_suspects(@_);
  30. }
  31.  
  32. sub set_suspects {
  33.     my $class = shift;
  34.     my $self = ref($class) ? $class : $Encode::Encoding{$Canon};
  35.     $self->{Suspects} = {%DEF_SUSPECTS};
  36.     $self->add_suspects(@_);
  37. }
  38.  
  39. sub add_suspects {
  40.     my $class = shift;
  41.     my $self = ref($class) ? $class : $Encode::Encoding{$Canon};
  42.     for my $c (@_) {
  43.         my $e = find_encoding($c) or die "Unknown encoding: $c";
  44.         $self->{Suspects}{ $e->name } = $e;
  45.         DEBUG and warn "Added: ", $e->name;
  46.     }
  47. }
  48.  
  49. sub decode($$;$) {
  50.     my ( $obj, $octet, $chk ) = @_;
  51.     my $guessed = guess( $obj, $octet );
  52.     unless ( ref($guessed) ) {
  53.         require Carp;
  54.         Carp::croak($guessed);
  55.     }
  56.     my $utf8 = $guessed->decode( $octet, $chk );
  57.     $_[1] = $octet if $chk;
  58.     return $utf8;
  59. }
  60.  
  61. sub guess_encoding {
  62.     guess( $Encode::Encoding{$Canon}, @_ );
  63. }
  64.  
  65. sub guess {
  66.     my $class = shift;
  67.     my $obj   = ref($class) ? $class : $Encode::Encoding{$Canon};
  68.     my $octet = shift;
  69.  
  70.     # sanity check
  71.     return unless defined $octet and length $octet;
  72.  
  73.     # cheat 0: utf8 flag;
  74.     if ( Encode::is_utf8($octet) ) {
  75.         return find_encoding('utf8') unless $NoUTFAutoGuess;
  76.         Encode::_utf8_off($octet);
  77.     }
  78.  
  79.     # cheat 1: BOM
  80.     use Encode::Unicode;
  81.     unless ($NoUTFAutoGuess) {
  82.         my $BOM = pack( 'C3', unpack( "C3", $octet ) );
  83.         return find_encoding('utf8')
  84.           if ( defined $BOM and $BOM eq $UTF8_BOM );
  85.         $BOM = unpack( 'N', $octet );
  86.         return find_encoding('UTF-32')
  87.           if ( defined $BOM and ( $BOM == 0xFeFF or $BOM == 0xFFFe0000 ) );
  88.         $BOM = unpack( 'n', $octet );
  89.         return find_encoding('UTF-16')
  90.           if ( defined $BOM and ( $BOM == 0xFeFF or $BOM == 0xFFFe ) );
  91.         if ( $octet =~ /\x00/o )
  92.         {    # if \x00 found, we assume UTF-(16|32)(BE|LE)
  93.             my $utf;
  94.             my ( $be, $le ) = ( 0, 0 );
  95.             if ( $octet =~ /\x00\x00/o ) {    # UTF-32(BE|LE) assumed
  96.                 $utf = "UTF-32";
  97.                 for my $char ( unpack( 'N*', $octet ) ) {
  98.                     $char & 0x0000ffff and $be++;
  99.                     $char & 0xffff0000 and $le++;
  100.                 }
  101.             }
  102.             else {                            # UTF-16(BE|LE) assumed
  103.                 $utf = "UTF-16";
  104.                 for my $char ( unpack( 'n*', $octet ) ) {
  105.                     $char & 0x00ff and $be++;
  106.                     $char & 0xff00 and $le++;
  107.                 }
  108.             }
  109.             DEBUG and warn "$utf, be == $be, le == $le";
  110.             $be == $le
  111.               and return
  112.               "Encodings ambiguous between $utf BE and LE ($be, $le)";
  113.             $utf .= ( $be > $le ) ? 'BE' : 'LE';
  114.             return find_encoding($utf);
  115.         }
  116.     }
  117.     my %try = %{ $obj->{Suspects} };
  118.     for my $c (@_) {
  119.         my $e = find_encoding($c) or die "Unknown encoding: $c";
  120.         $try{ $e->name } = $e;
  121.         DEBUG and warn "Added: ", $e->name;
  122.     }
  123.     my $nline = 1;
  124.     for my $line ( split /\r\n?|\n/, $octet ) {
  125.  
  126.         # cheat 2 -- \e in the string
  127.         if ( $line =~ /\e/o ) {
  128.             my @keys = keys %try;
  129.             delete @try{qw/utf8 ascii/};
  130.             for my $k (@keys) {
  131.                 ref( $try{$k} ) eq 'Encode::XS' and delete $try{$k};
  132.             }
  133.         }
  134.         my %ok = %try;
  135.  
  136.         # warn join(",", keys %try);
  137.         for my $k ( keys %try ) {
  138.             my $scratch = $line;
  139.             $try{$k}->decode( $scratch, FB_QUIET );
  140.             if ( $scratch eq '' ) {
  141.                 DEBUG and warn sprintf( "%4d:%-24s ok\n", $nline, $k );
  142.             }
  143.             else {
  144.                 use bytes ();
  145.                 DEBUG
  146.                   and warn sprintf( "%4d:%-24s not ok; %d bytes left\n",
  147.                     $nline, $k, bytes::length($scratch) );
  148.                 delete $ok{$k};
  149.             }
  150.         }
  151.         %ok or return "No appropriate encodings found!";
  152.         if ( scalar( keys(%ok) ) == 1 ) {
  153.             my ($retval) = values(%ok);
  154.             return $retval;
  155.         }
  156.         %try = %ok;
  157.         $nline++;
  158.     }
  159.     $try{ascii}
  160.       or return "Encodings too ambiguous: ", join( " or ", keys %try );
  161.     return $try{ascii};
  162. }
  163.  
  164. 1;
  165. __END__
  166.  
  167. =head1 NAME
  168.  
  169. Encode::Guess -- Guesses encoding from data
  170.  
  171. =head1 SYNOPSIS
  172.  
  173.   # if you are sure $data won't contain anything bogus
  174.  
  175.   use Encode;
  176.   use Encode::Guess qw/euc-jp shiftjis 7bit-jis/;
  177.   my $utf8 = decode("Guess", $data);
  178.   my $data = encode("Guess", $utf8);   # this doesn't work!
  179.  
  180.   # more elaborate way
  181.   use Encode::Guess;
  182.   my $enc = guess_encoding($data, qw/euc-jp shiftjis 7bit-jis/);
  183.   ref($enc) or die "Can't guess: $enc"; # trap error this way
  184.   $utf8 = $enc->decode($data);
  185.   # or
  186.   $utf8 = decode($enc->name, $data)
  187.  
  188. =head1 ABSTRACT
  189.  
  190. Encode::Guess enables you to guess in what encoding a given data is
  191. encoded, or at least tries to.  
  192.  
  193. =head1 DESCRIPTION
  194.  
  195. By default, it checks only ascii, utf8 and UTF-16/32 with BOM.
  196.  
  197.   use Encode::Guess; # ascii/utf8/BOMed UTF
  198.  
  199. To use it more practically, you have to give the names of encodings to
  200. check (I<suspects> as follows).  The name of suspects can either be
  201. canonical names or aliases.
  202.  
  203. CAVEAT: Unlike UTF-(16|32), BOM in utf8 is NOT AUTOMATICALLY STRIPPED.
  204.  
  205.  # tries all major Japanese Encodings as well
  206.   use Encode::Guess qw/euc-jp shiftjis 7bit-jis/;
  207.  
  208. If the C<$Encode::Guess::NoUTFAutoGuess> variable is set to a true
  209. value, no heuristics will be applied to UTF8/16/32, and the result
  210. will be limited to the suspects and C<ascii>.
  211.  
  212. =over 4
  213.  
  214. =item Encode::Guess->set_suspects
  215.  
  216. You can also change the internal suspects list via C<set_suspects>
  217. method. 
  218.  
  219.   use Encode::Guess;
  220.   Encode::Guess->set_suspects(qw/euc-jp shiftjis 7bit-jis/);
  221.  
  222. =item Encode::Guess->add_suspects
  223.  
  224. Or you can use C<add_suspects> method.  The difference is that
  225. C<set_suspects> flushes the current suspects list while
  226. C<add_suspects> adds.
  227.  
  228.   use Encode::Guess;
  229.   Encode::Guess->add_suspects(qw/euc-jp shiftjis 7bit-jis/);
  230.   # now the suspects are euc-jp,shiftjis,7bit-jis, AND
  231.   # euc-kr,euc-cn, and big5-eten
  232.   Encode::Guess->add_suspects(qw/euc-kr euc-cn big5-eten/);
  233.  
  234. =item Encode::decode("Guess" ...)
  235.  
  236. When you are content with suspects list, you can now
  237.  
  238.   my $utf8 = Encode::decode("Guess", $data);
  239.  
  240. =item Encode::Guess->guess($data)
  241.  
  242. But it will croak if:
  243.  
  244. =over
  245.  
  246. =item *
  247.  
  248. Two or more suspects remain
  249.  
  250. =item *
  251.  
  252. No suspects left
  253.  
  254. =back
  255.  
  256. So you should instead try this;
  257.  
  258.   my $decoder = Encode::Guess->guess($data);
  259.  
  260. On success, $decoder is an object that is documented in
  261. L<Encode::Encoding>.  So you can now do this;
  262.  
  263.   my $utf8 = $decoder->decode($data);
  264.  
  265. On failure, $decoder now contains an error message so the whole thing
  266. would be as follows;
  267.  
  268.   my $decoder = Encode::Guess->guess($data);
  269.   die $decoder unless ref($decoder);
  270.   my $utf8 = $decoder->decode($data);
  271.  
  272. =item guess_encoding($data, [, I<list of suspects>])
  273.  
  274. You can also try C<guess_encoding> function which is exported by
  275. default.  It takes $data to check and it also takes the list of
  276. suspects by option.  The optional suspect list is I<not reflected> to
  277. the internal suspects list.
  278.  
  279.   my $decoder = guess_encoding($data, qw/euc-jp euc-kr euc-cn/);
  280.   die $decoder unless ref($decoder);
  281.   my $utf8 = $decoder->decode($data);
  282.   # check only ascii and utf8
  283.   my $decoder = guess_encoding($data);
  284.  
  285. =back
  286.  
  287. =head1 CAVEATS
  288.  
  289. =over 4
  290.  
  291. =item *
  292.  
  293. Because of the algorithm used, ISO-8859 series and other single-byte
  294. encodings do not work well unless either one of ISO-8859 is the only
  295. one suspect (besides ascii and utf8).
  296.  
  297.   use Encode::Guess;
  298.   # perhaps ok
  299.   my $decoder = guess_encoding($data, 'latin1');
  300.   # definitely NOT ok
  301.   my $decoder = guess_encoding($data, qw/latin1 greek/);
  302.  
  303. The reason is that Encode::Guess guesses encoding by trial and error.
  304. It first splits $data into lines and tries to decode the line for each
  305. suspect.  It keeps it going until all but one encoding is eliminated
  306. out of suspects list.  ISO-8859 series is just too successful for most
  307. cases (because it fills almost all code points in \x00-\xff).
  308.  
  309. =item *
  310.  
  311. Do not mix national standard encodings and the corresponding vendor
  312. encodings.
  313.  
  314.   # a very bad idea
  315.   my $decoder
  316.      = guess_encoding($data, qw/shiftjis MacJapanese cp932/);
  317.  
  318. The reason is that vendor encoding is usually a superset of national
  319. standard so it becomes too ambiguous for most cases.
  320.  
  321. =item *
  322.  
  323. On the other hand, mixing various national standard encodings
  324. automagically works unless $data is too short to allow for guessing.
  325.  
  326.  # This is ok if $data is long enough
  327.  my $decoder =  
  328.   guess_encoding($data, qw/euc-cn
  329.                            euc-jp shiftjis 7bit-jis
  330.                            euc-kr
  331.                            big5-eten/);
  332.  
  333. =item *
  334.  
  335. DO NOT PUT TOO MANY SUSPECTS!  Don't you try something like this!
  336.  
  337.   my $decoder = guess_encoding($data, 
  338.                                Encode->encodings(":all"));
  339.  
  340. =back
  341.  
  342. It is, after all, just a guess.  You should alway be explicit when it
  343. comes to encodings.  But there are some, especially Japanese,
  344. environment that guess-coding is a must.  Use this module with care. 
  345.  
  346. =head1 TO DO
  347.  
  348. Encode::Guess does not work on EBCDIC platforms.
  349.  
  350. =head1 SEE ALSO
  351.  
  352. L<Encode>, L<Encode::Encoding>
  353.  
  354. =cut
  355.  
  356.